Hace un tiempo ya hablé de MDWiki como una forma sencilla de publicar documentos en formato markdown en la web sin tener que pasar por el engorro de convertirlos primero a HTML. Como en el aquel artículo sobre Documentos colgados en Google Drive no explicaba cómo hacerlo, he pensado en crear varias entradas nuevas: sobre cómo utilizar MDWiki con Google Drive, la integración de MDWiki y los repositorios de Bitbucket, etc.
En esta primera entrada de hoy hablaré de las diferencias entre los dos métodos para que puedas elegir el sistema que mejor se adapte a tus necesidades.
Entre las bibliotecas que incorpora MDwiki se encuentra, por ejemplo, Bootstrap, lo que permite que la web publicada aproveche todas sus funcionalidades: responsive (se adapta en función de la pantalla del dispositivo en el que se visualiza el contenido), con un aspecto limpio y cuidado directo de fábrica, de manera que no es necesario definir hojas de estilo para que tus documentos tengan un aspecto atractivo, etc... Y al estar basado en Bootstrap, puedes cambiar rápidamente el aspecto de tu sitio mediante el uso de Bootswatch.
En este apartado de la web de MDwiki puedes ver todas las bibliotecas de código que incorpora: Credits / Technologies.
Al principio, hace muuucho tiempo, si querías publicar documentos en internet, necesitabas un dominio, un servidor web, un cliente FTP para subir los archivos... Podías crear/editar los ficheros HTML directamente en un editor de texto, o utilizar alguna cosa como Netscape Composer o Microsoft FrontPage. Después, los subías por FTP a tu sitio web.
Las cosas han cambiado mucho desde entonces y han avanzado hasta una internet de plataformas. Hoy en día, si quieres publicar algo en internet, utilizas cualquiera de los servicios disponibles para ello. Blogs, vídeos, música, lo que sea. El problema es cuando sólo quieres publicar un sitio web sencillo, una página web con información sobre tu negocio, con tu currículum online o documentación sobre un evento o proyecto en el que estás trabajando. La gratuidad de los servicios de alojamiento de webs simples viene asociada, en la mayoría de los casos, a la presencia de publicidad indiscriminada.
Ninguna de estas alternativas encajaba con la idea de publicar documentos o manuales variados en un solo sitio. En un blog las entradas están organizadas temporalmente, pero la documentación no se organiza de esa manera. Hasta ahora utilizaba Google Drive para alojar sitios web realizados en HTML, como Primeros pasos con Backbone.js, pero como he dicho antes, lo de editar ficheros HTML a pelo es un verdadero pain in the ass, que dicen los angloparlantes. Además, mi idea era reunir en un único sitio todos los documentos que voy publicando y con Google Drive no se me ha ocurrido cómo relacionar los diferentes manuales en una página central que sirva de índice.
MDwiki soluciona estos dos problemas: por un lado, puedo usar markdown para redactar los documentos, lo que resulta muy sencillo y ágil, ya que resulta completamente natural y no interfiere con el proceso de escritura.
Por otro lado, MDwiki permite utilizar una barra de navegación superior desde donde enlazar a diferentes secciones del sitio web o, en mi caso, servir de punto central de navegación entre los diferentes proyectos de la documentación. Esta barra de navegación superior es un fichero llamado navigation.md, que también es fichero en formato Markdown. ¡Así que problema resuelto!
En la ayuda oficial de Google tienes indicados los pasos para publicar un documento web alojado en Google Drive.
Yo quiero centrarme en las ventajas e inconvenientes de usar específicamente Google Drive con MDwiki para publicar documentos.
Una de las principales ventajas de Google Drive es que seguramente ya dispones de una cuenta de GMail y por tanto, no necesitas darte de alta en ningún otro sitio. Para mantener organizados todos los documentos publicados en Google Drive con MDwiki, creé una carpeta llamada www (aunque puedes llamarla web, o de cualquier otra manera). Dentro de esta carpeta es donde colgué el fichero mdwiki.html, renombrado a index.html (y publicado después en internet siguiendo las instrucciones de Google).
El problema de publicar documentos web en Google Drive es que la URL (la dirección web) del documento es extraordinariamente larga:
Una forma de solucionar este problema es usando un acortador de URLs y convertirlo en algo como: https://goo.gl/mNkdmk. Tampoco es una panacea, pero resulta más asequible. Otros servicios como Bitly permiten personalizar el enlace, así que podrías usar algo más descriptivo, como http://bit.ly/mdwikidocs.
Una de las ventajas de usar Google Drive con MDwiki es que puedes editar los ficheros en formato markdown directamente desde el navegador. Es necesario que vincules una aplicación con Google Drive para poder editar los ficheros markdown; personalmente utilizo Drive Notepad; probablemente no será la aplicación más chula del mundo, pero a mi me sirve, es gratuita y nunca me ha dado ningún problema. Así que si quiero editar cualquier documento colgado en Google Drive con MDwiki, hago click con el botón derecho, Abrir con, Drive Notepad y listo!
Una de las desventajas de usar Google Drive para los documentos publicados con MDwiki es que, como no tengo instalado Google Drive en mi equipo físico, no es fácil mantener sincronizados los documentos locales en mi equipo con los documentos publicados. Obviamente, la solución es tan sencilla como instalar el cliente para Google Drive...
Personalmente prefiero usar BitBucket, ya que ofrece ilimitados repositorios privados. Del mismo modo que con Google Docs, el primer paso es habilitar la publicación de sitios web estáticos. La documentación depende de cada servicio específico por lo que quizás tengas que buscar qué pasos seguir en cada caso concreto. Para BitBucket, las instrucciones están en Publishing a Website on Bitbucket (en inglés). Mi intención es traducir estas instrucciones al castellano más adelante.
Una de las ventajas respecto a la publicación en Google Drive es que la URL de los documentos publicados es mucho más sencilla: http://xaviaznar.bitbucket.org/#!index.md (la parte frente a bitbucket.org es el nombre de tu cuenta en este servicio).
Desde la web de BitBucket puedes editar la documentación publicada sin necesidad de instalar nada, aunque las diferentes ediciones se consideran nuevos commits. Así, si realizas modificaciones de la documentación localmente en tu equipo, debes realizar un pull y gestionar los posibles conflictos que se ocasiones antes de poder actualizar con los contenidos de tu repositorio local.
Obviamente, si usas git ya estarás habituado a este flujo de trabajo, así que no resulta un problema adicional. El uso de un sistema de control de versiones también facilita colaborar con otros miembros para mantener la documentación, por ejemplo. Y siempre con la ventaja de tener un registro de todos los cambios que se han ido realizando en la documentación.
Aunque claro, si no utilizas git, todas estas opciones resultan un obstáculo más que una ventaja. Este segundo método quizás sea más adecuada para aquellas personas que se sientan cómodas trabajando con git y que quieran publicar manuales o documentación de sus proyectos de manera sencilla, usando -probablemente- las mismas herramientas que utilicen para gestionar el código de sus proyectos.
En esta primera entrada de hoy hablaré de las diferencias entre los dos métodos para que puedas elegir el sistema que mejor se adapte a tus necesidades.
¿Qué es MDWiki y para qué sirve?
En primer lugar, empezaré con una breve descripción de qué es MDwiki. MDwiki es un proyecto alojado en GitHub que reúne diferentes bibliotecas públicas de código para crear un producto muy interesante. El objetivo principal de MDwiki es transformar un fichero en formato markdown en un fichero en formato HTML. La conversión se realiza completamente en el navegador del usuario, por lo que no requiere ningún tipo de infraestructura o lenguaje de scripting en el servidor (nada de PHP, python, ruby o cualquier otro). El fichero se publica en directamente en formato markdown en el servidor web, a diferencia de lo que ocurre con los generadores de sitios estáticos. Estos generadores convierten el fichero markdown a un conjunto de ficheros html, web y css que después hay que subir a un servidor web. En este aspecto, con MDwiki resulta mucho más sencillo publicar y actualizar ficheros en la web. Además de la agilidad a la hora de publicar, el hecho de no requerir ningún tipo de procesamiento en el servidor te permite aprovechar la capacidad de servir sitios web estáticos que ofrecen muchos servicios de alojamiento de ficheros gratuitos, como Google Drive, GitHub, BitBucket, etc...Entre las bibliotecas que incorpora MDwiki se encuentra, por ejemplo, Bootstrap, lo que permite que la web publicada aproveche todas sus funcionalidades: responsive (se adapta en función de la pantalla del dispositivo en el que se visualiza el contenido), con un aspecto limpio y cuidado directo de fábrica, de manera que no es necesario definir hojas de estilo para que tus documentos tengan un aspecto atractivo, etc... Y al estar basado en Bootstrap, puedes cambiar rápidamente el aspecto de tu sitio mediante el uso de Bootswatch.
En este apartado de la web de MDwiki puedes ver todas las bibliotecas de código que incorpora: Credits / Technologies.
¿Por qué uso MDwiki?
Como apunta su propio nombre, MDwiki se inspira en la agilidad y sencillez de los wikis para publicar información en internet de manera rápida. A la hora de crear documentación o de escribir cualquier texto con la intención de publicarlo en la web, usar Markdown es una de las opciones que se van imponiendo, especialmente entre usuarios técnicos.Al principio, hace muuucho tiempo, si querías publicar documentos en internet, necesitabas un dominio, un servidor web, un cliente FTP para subir los archivos... Podías crear/editar los ficheros HTML directamente en un editor de texto, o utilizar alguna cosa como Netscape Composer o Microsoft FrontPage. Después, los subías por FTP a tu sitio web.
Las cosas han cambiado mucho desde entonces y han avanzado hasta una internet de plataformas. Hoy en día, si quieres publicar algo en internet, utilizas cualquiera de los servicios disponibles para ello. Blogs, vídeos, música, lo que sea. El problema es cuando sólo quieres publicar un sitio web sencillo, una página web con información sobre tu negocio, con tu currículum online o documentación sobre un evento o proyecto en el que estás trabajando. La gratuidad de los servicios de alojamiento de webs simples viene asociada, en la mayoría de los casos, a la presencia de publicidad indiscriminada.
Ninguna de estas alternativas encajaba con la idea de publicar documentos o manuales variados en un solo sitio. En un blog las entradas están organizadas temporalmente, pero la documentación no se organiza de esa manera. Hasta ahora utilizaba Google Drive para alojar sitios web realizados en HTML, como Primeros pasos con Backbone.js, pero como he dicho antes, lo de editar ficheros HTML a pelo es un verdadero pain in the ass, que dicen los angloparlantes. Además, mi idea era reunir en un único sitio todos los documentos que voy publicando y con Google Drive no se me ha ocurrido cómo relacionar los diferentes manuales en una página central que sirva de índice.
MDwiki soluciona estos dos problemas: por un lado, puedo usar markdown para redactar los documentos, lo que resulta muy sencillo y ágil, ya que resulta completamente natural y no interfiere con el proceso de escritura.
Por otro lado, MDwiki permite utilizar una barra de navegación superior desde donde enlazar a diferentes secciones del sitio web o, en mi caso, servir de punto central de navegación entre los diferentes proyectos de la documentación. Esta barra de navegación superior es un fichero llamado navigation.md, que también es fichero en formato Markdown. ¡Así que problema resuelto!
MDwiki y Google Drive
En la página oficial de MDwiki tienes un tutorial sobre cómo utilizar MDwiki con Google Drive.En la ayuda oficial de Google tienes indicados los pasos para publicar un documento web alojado en Google Drive.
Yo quiero centrarme en las ventajas e inconvenientes de usar específicamente Google Drive con MDwiki para publicar documentos.
Una de las principales ventajas de Google Drive es que seguramente ya dispones de una cuenta de GMail y por tanto, no necesitas darte de alta en ningún otro sitio. Para mantener organizados todos los documentos publicados en Google Drive con MDwiki, creé una carpeta llamada www (aunque puedes llamarla web, o de cualquier otra manera). Dentro de esta carpeta es donde colgué el fichero mdwiki.html, renombrado a index.html (y publicado después en internet siguiendo las instrucciones de Google).
El problema de publicar documentos web en Google Drive es que la URL (la dirección web) del documento es extraordinariamente larga:
https://www.googledrive.com/host/0Bzky3aU2486jfjVJdWFMaEdPZFVJaGR1RjFjTGdrU1VnU0VoZ3g1Qm5lcjA2MGhraWRVZFUEsta dirección, ya de por sí larga, se expande después hasta:
https://4f2400ad69e060d7f9f5ce053d183ebe23769f29-www.googledrive.com/host/0Bzky3aU2486jfjVJdWFMaEdPZFVJaGR1RjFjTGdrU1VnU0VoZ3g1Qm5lcjA2MGhraWRVZFU/#!index.mdAsí que no es nada sencillo de recordar o escribir, si tienes que hacerlo de forma manual. Tampoco da una pista de qué es lo que se esconde tras la URL, ni quién es su autor, ni nada por el estilo.
Una forma de solucionar este problema es usando un acortador de URLs y convertirlo en algo como: https://goo.gl/mNkdmk. Tampoco es una panacea, pero resulta más asequible. Otros servicios como Bitly permiten personalizar el enlace, así que podrías usar algo más descriptivo, como http://bit.ly/mdwikidocs.
Una de las ventajas de usar Google Drive con MDwiki es que puedes editar los ficheros en formato markdown directamente desde el navegador. Es necesario que vincules una aplicación con Google Drive para poder editar los ficheros markdown; personalmente utilizo Drive Notepad; probablemente no será la aplicación más chula del mundo, pero a mi me sirve, es gratuita y nunca me ha dado ningún problema. Así que si quiero editar cualquier documento colgado en Google Drive con MDwiki, hago click con el botón derecho, Abrir con, Drive Notepad y listo!
Una de las desventajas de usar Google Drive para los documentos publicados con MDwiki es que, como no tengo instalado Google Drive en mi equipo físico, no es fácil mantener sincronizados los documentos locales en mi equipo con los documentos publicados. Obviamente, la solución es tan sencilla como instalar el cliente para Google Drive...
MDwiki y BitBucket (o GitHub)
Esta opción es algo más técnica, orientada a usuarios que utilicen git o algún otro sistema de control de versiones. En este caso, aprovechamos que tanto BitBucket como GitHub ofrecen la posibilidad de publicar sitios web estáticos con los documentos alojados en sus repositorios.Personalmente prefiero usar BitBucket, ya que ofrece ilimitados repositorios privados. Del mismo modo que con Google Docs, el primer paso es habilitar la publicación de sitios web estáticos. La documentación depende de cada servicio específico por lo que quizás tengas que buscar qué pasos seguir en cada caso concreto. Para BitBucket, las instrucciones están en Publishing a Website on Bitbucket (en inglés). Mi intención es traducir estas instrucciones al castellano más adelante.
Una de las ventajas respecto a la publicación en Google Drive es que la URL de los documentos publicados es mucho más sencilla: http://xaviaznar.bitbucket.org/#!index.md (la parte frente a bitbucket.org es el nombre de tu cuenta en este servicio).
Desde la web de BitBucket puedes editar la documentación publicada sin necesidad de instalar nada, aunque las diferentes ediciones se consideran nuevos commits. Así, si realizas modificaciones de la documentación localmente en tu equipo, debes realizar un pull y gestionar los posibles conflictos que se ocasiones antes de poder actualizar con los contenidos de tu repositorio local.
Obviamente, si usas git ya estarás habituado a este flujo de trabajo, así que no resulta un problema adicional. El uso de un sistema de control de versiones también facilita colaborar con otros miembros para mantener la documentación, por ejemplo. Y siempre con la ventaja de tener un registro de todos los cambios que se han ido realizando en la documentación.
Aunque claro, si no utilizas git, todas estas opciones resultan un obstáculo más que una ventaja. Este segundo método quizás sea más adecuada para aquellas personas que se sientan cómodas trabajando con git y que quieran publicar manuales o documentación de sus proyectos de manera sencilla, usando -probablemente- las mismas herramientas que utilicen para gestionar el código de sus proyectos.
Resumen
En resumen, el primer método es más sencillo si eres un usuario que ha dado el primer paso y se siente cómodo escribiendo en formato markdown, pero que todavía no utiliza un sistema de control de versiones. Con Google Drive la única pega son las URLs kilométricas, pero no es nada que un buen servicio de acortar URLs no pueda solucionar.
En cuanto al método de usar las páginas web de BitBucket (o GitHub) son el método ideal si ya utilizas Git y quieres publicar documentación, además del código de tu proyecto.
Comentarios